<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Create or update application privileges API | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="security-api.html" title="Security APIs">
<link rel="prev" href="security-api-create-api-key.html" title="Create API key API">
<link rel="next" href="security-api-put-role-mapping.html" title="Create or update role mappings API">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="rest-apis.html">REST APIs</a></span>
»
<span class="breadcrumb-link"><a href="security-api.html">Security APIs</a></span>
»
<span class="breadcrumb-node">Create or update application privileges API</span>
</div>
<div class="navheader">
<span class="prev">
<a href="security-api-create-api-key.html">« Create API key API</a>
</span>
<span class="next">
<a href="security-api-put-role-mapping.html">Create or update role mappings API »</a>
</span>
</div>
<div class="section xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="security-api-put-privileges"></a>Create or update application privileges API<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc">edit</a><a class="xpack_tag" href="/subscriptions"></a>
</h2>
</div></div></div>

<p>Adds or updates <a class="xref" href="security-privileges.html#application-privileges" title="Application privileges">application privileges</a>.</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-put-privileges-request"></a>Request<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc">edit</a>
</h3>
</div></div></div>
<p><code class="literal">POST /_security/privilege</code><br></p>
<p><code class="literal">PUT /_security/privilege</code></p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-put-privileges-prereqs"></a>Prerequisites<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc">edit</a>
</h3>
</div></div></div>
<p>To use this API, you must have either:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
the <code class="literal">manage_security</code> cluster privilege (or a greater privilege such as <code class="literal">all</code>); <em>or</em>
</li>
<li class="listitem">
the <em>"Manage Application Privileges"</em> global privilege for the application
being referenced in the request
</li>
</ul>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-put-privileges-desc"></a>Description<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc">edit</a>
</h3>
</div></div></div>
<p>This API creates or updates privileges. To remove privileges, use the
<a class="xref" href="security-api-delete-privilege.html" title="Delete application privileges API">delete application privilege API</a>.</p>
<p>For more information, see <a class="xref" href="defining-roles.html#roles-application-priv" title="Application Privileges">Application Privileges</a>.</p>
<p>To check a user’s application privileges, use the
<a class="xref" href="security-api-has-privileges.html" title="Has privileges API">has privileges API</a>.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-put-privileges-request-body"></a>Request body<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The body is a JSON object where the names of the fields are the application
names and the value of each field is an object. The fields in this inner
object are the names of the privileges and each value is a JSON object that
includes the following fields:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">actions</code>
</span>
</dt>
<dd>
(array-of-string) A list of action names that are granted by this
privilege. This field must exist and cannot be an empty array.
</dd>
<dt>
<span class="term">
<code class="literal">metadata</code>
</span>
</dt>
<dd>
(object) Optional meta-data. Within the <code class="literal">metadata</code> object, keys
that begin with <code class="literal">_</code> are reserved for system usage.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-app-privileges-validation"></a>Validation<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
Application names
</span>
</dt>
<dd>
<p>
Application names are formed from a <em>prefix</em>, with an optional <em>suffix</em> that
conform to the following rules:
</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
The prefix must begin with a lowercase ASCII letter
</li>
<li class="listitem">
The prefix must contain only ASCII letters or digits
</li>
<li class="listitem">
The prefix must be at least 3 characters long
</li>
<li class="listitem">
If the suffix exists, it must begin with either <code class="literal">-</code> or <code class="literal">_</code>
</li>
<li class="listitem">
The suffix cannot contain any of the following characters:
<code class="literal">\</code>, <code class="literal">/</code>, <code class="literal">*</code>, <code class="literal">?</code>, <code class="literal">"</code>, <code class="literal">&lt;</code>, <code class="literal">&gt;</code>, <code class="literal">|</code>, <code class="literal">,</code>, <code class="literal">*</code>
</li>
<li class="listitem">
No part of the name can contain whitespace.
</li>
</ul>
</div>
</dd>
<dt>
<span class="term">
Privilege names
</span>
</dt>
<dd>
Privilege names must begin with a lowercase ASCII letter and must contain
only ASCII letters and digits along with the characters <code class="literal">_</code>, <code class="literal">-</code> and <code class="literal">.</code>
</dd>
<dt>
<span class="term">
Action names
</span>
</dt>
<dd>
Action names can contain any number of printable ASCII characters and must
contain at least one of the following characters: <code class="literal">/</code> <code class="literal">*</code>, <code class="literal">:</code>
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-put-privileges-response-body"></a>Response body<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc">edit</a>
</h3>
</div></div></div>
<p>A successful call returns a JSON structure that shows whether the privilege has
been created or updated.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-put-privileges-example"></a>Examples<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc">edit</a>
</h3>
</div></div></div>
<p>To add a single privilege, submit a PUT or POST request to the
<code class="literal">/_security/privilege/</code> endpoint. For example:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /_security/privilege
{
  "myapp": {
    "read": {
      "actions": [ <a id="CO650-1"></a><i class="conum" data-value="1"></i>
        "data:read/*" , <a id="CO650-2"></a><i class="conum" data-value="2"></i>
        "action:login" ],
        "metadata": { <a id="CO650-3"></a><i class="conum" data-value="3"></i>
          "description": "Read access to myapp"
        }
      }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2066.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO650-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>These strings have significance within the "myapp" application. Elasticsearch does not
assign any meaning to them.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO650-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>The use of a wildcard here (<code class="literal">*</code>) means that this privilege grants access to
all actions that start with <code class="literal">data:read/</code>. Elasticsearch does not assign any meaning
to these actions. However, if the request includes an application privilege
such as <code class="literal">data:read/users</code> or <code class="literal">data:read/settings</code>, the
<a class="xref" href="security-api-has-privileges.html" title="Has privileges API">has privileges API</a> respects the use of a
wildcard and returns <code class="literal">true</code>.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO650-3"><i class="conum" data-value="3"></i></a></p>
</td>
<td align="left" valign="top">
<p>The metadata object is optional.</p>
</td>
</tr>
</table>
</div>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "myapp": {
    "read": {
      "created": true <a id="CO651-1"></a><i class="conum" data-value="1"></i>
    }
  }
}</pre>
</div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO651-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>When an existing privilege is updated, <code class="literal">created</code> is set to false.</p>
</td>
</tr>
</table>
</div>
<p>To add multiple privileges, submit a POST request to the
<code class="literal">/_security/privilege/</code> endpoint. For example:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /_security/privilege
{
  "app01": {
    "read": {
      "actions": [ "action:login", "data:read/*" ]
    },
    "write": {
      "actions": [ "action:login", "data:write/*" ]
    }
  },
  "app02": {
    "all": {
      "actions": [ "*" ]
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2067.console"></div>
<p>A successful call returns a JSON structure that shows whether the privileges
have been created or updated.</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "app02": {
    "all": {
      "created": true
    }
  },
  "app01": {
    "read": {
      "created": true
    },
    "write": {
      "created": true
    }
  }
}</pre>
</div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="security-api-create-api-key.html">« Create API key API</a>
</span>
<span class="next">
<a href="security-api-put-role-mapping.html">Create or update role mappings API »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
